4.1: Editable Table Control

Editable Tables allow rows of data to be inserted, modified and deleted. The information in these tables is read-only by default, but rows can be clicked to make them editable, with the ability to accept or discard modifications. Each row also has a delete button that can be used to remove the row and controls are provided at the bottom of the table for the insertion of new entries into the table. When this control is added to the page, a couple of fields are created by default initially (table_field1 and table_field2). You can modify or remove these fields and add additional controls as required. The table can contain different types of data entry controls as needed, including select boxes, radio buttons, and checkboxes. If you have added fields from a data source you will probably need to change the bindings for the ‘EditableTable’ repeat (and possibly the contained controls) to ensure the correct data is displayed. This can be done from the Bindings tab. This control uses an additional JavaScript file, which will be automatically linked to your page when you add the control. In normal operation, all the changes made to data in the table are stored on the client side until a submission event occurs (Please see sections on Controllers if required). It is possible to configure a table to communicate with the server after every change. For more information on this, please have a look at this post on the forum. At the bottom of the control, there is be a custom field called table_init. This contains a script fragment that initialises the editable table functionality, and specifies the configuration options that apply to it. It is important that the position of this custom field is not changed, but you are free to adjust the configuration options as required. Any options not provided will take their default values as indicated in the table below. Table of Editable Table Configuration Options

Configuration Option	Description
validate	Boolean value indicating whether the user's data should be validated before inserting new rows, or accepting the changes to existing rows. If true (the default) it will not be possible to insert or modify data that doesn't pass validation.
allow_add	Boolean value indicating whether the user should be able to add new rows to the table. If this is false, then the controls for adding a new entry will not appear. From WebMaker 3.1.2 this option can also accept a function reference as detailed below. (default true)
allow_delete	Boolean value indicating whether the user should be able to delete rows from the table. If this is false, then the delete row buttons will not be shown. From WebMaker 3.1.2 this option can also accept a function reference as detailed below. (default true)
allow_edit	Boolean value indicating whether the user should be able to edit rows in the table. If this is false, then the edit buttons will not be shown. From WebMaker 3.1.2 this option can also accept a function reference as detailed below. (default true)
allow_reorder	From WebMaker 6. Boolean value indicating whether the user should be able to reorder the rows in the table. If this is true, then up and down arrows will be provided on each row to enable reordering. This option can also accept a function reference as detailed below. (default false)
change_function	Function reference (or name) that should be called whenever any change is made. Two parameters are passed to this function, a string indicating the type of change ('insert', 'remove', 'remove_complete', 'edit', 'reorder_up', 'reorder_down'), and the id of the row being changed. For most of these scenarios the function will be called after the event has occurred. For a remove operation however, the 'remove' type will be called before the remove takes place, and can return false to cancel the remove operation. Once a row has actually been removed the 'remove_complete' event type will be called.
single_click_edit	From WebMaker 8. Boolean value indicating whether the user can single click on the displayed text values to edit them, instead of requiring the edit button to be used. Only applies if editing is allowed. The default is set to true when new tables are added, but false if this parameter is omitted.
double_click_edit	From WebMaker 8. Boolean value indicating whether the user can double click on the displayed text values to edit them, instead of requiring the edit button to be used. Only applies if editing is allowed, and single_click_edit is not set to true. (default false)
show_edit_btn	From WebMaker 8. If set to false, the edit buttons will not be displayed even if editing is enabled. This should only be done if one of the above 'click to edit' options have been enabled. (default true)
force_accept_btn	From WebMaker 8. Boolean value controlling the accept changes behaviour. The default is set to false when new tables are added, but true if this parameter is omitted. If set to true, the user must click the Accept Changes button in order to store any changes made to a row. If set to false, then simply clicking outside the row, or pressing the enter key will store the changes.
show_insert_row	From WebMaker 8. Boolean value controlling the insert row behaviour, which applies if adding new rows is allowed. The default is set to false when new tables are added, but true if this parameter is omitted. If true, a row of empty controls will always be present at the bottom of the table, along with an insert button. Clicking the button will insert a new record using the values entered into these controls. If this option is set to false, then only the insert button will be visible at the bottom of the table. Clicking this in this mode will add a new blank row to the table which will be automatically shown in edit mode for the user to fill in the required details.
validate_function	From WebMaker 9. Optional function reference (or name) to perform additional validation checks. If validate is true, and this is provided, it will be called after the in built validation, passing through the type of operation (edit or insert), and the id of the relevant row. If this function returns false, then the insert/edit process will not continue.
display_format_function	From WebMaker 9. Optional function reference (or name) to perform additional formatting of the display values shown in each cell. If provided, this will receive two parameters, the cell object (td), and the display value that has already been determined. This function must return the display value to use.
sort_function	From WebMaker 9. Optional function reference (or name) for performing sorting of the table rows. If provided, this will be called a number of times with two tr objects, one for each row to compare. If the first row should come first return -1, if the second row should be first, return +1, if they are the same return 0. This should not be used in combination with the allow_reorder option.

Conditionally Allow Options As of WebMaker 3.1.2, all four of the allow_... parameters can be set to a function reference, instead of the boolean value. In this case, the specified function will be called when required to determine whether the relevant capability should be enabled. For allow_add and allow_reorder, the id of the table will be passed to the defined function. For allow_edit and allow_delete, the id of the table and the id of the relevant row within the table, will be passed to the defined functions. Each function must return a boolean value to indicate whether the capability should be enabled. This allows you to dynamically make decisions about when these capabilities should be enabled. For example, only allowing certain rows to be edited, or preventing some users from being able to insert new records. Customising Display Strings It is also possible to override the displayed message strings used within the table. For example, the caption string on the insert button, or the hover tooltips can be overriden. This is done by adding an additional messages property to the configuration settings. This should be an object that defines all the messages you would like to override. The full list of supported values is as follows: insertBtn, insertBtnTitle, editBtn, editBtnTitle, removeBtn, removeBtnTitle, acceptBtn, acceptBtnTitle, cancelBtn, cancelBtnTitle, reorderUpBtn, reorderUpBtnTitle, reorderDownBtn, reorderDownBtnTitle, clickToEditRowTitle, doubleClickToEditRowTitle . Please note that most themes use images in place of text for some of the buttons. Therefore, not all of these strings will always be visible.

hyf.editabletable.init(hyf.editabletable.getLastTableOutput(), {
					validate:true,
					...
					messages: {
						insertBtn: 'Add New Row',
						insertBtnTitle: 'Click to add a new row of data to the table'
					}
				});
				

This capability could be used in conjunction with the Display Variables capability to help with the support of multi-lingual applications. First, you would define a display variable for each text string you want to customise, and then configure the messages parameter to get the values from display variables. e.g insertBtn: hyf.util.getDisplayVariableValue('display variable name'). You can then use the standard translation files to provide the correct translated values for each display variable. Please see the section on Multi Lingual Applications under the sections on Controllers for for more details.